package edu.cs.usask.ca.silver.api.businesslogic;

import edu.cs.usask.ca.silver.api.persistence.StorageI;
import edu.cs.usask.ca.silver.businesslogic.ids.ParameterID;
import edu.cs.usask.ca.silver.businesslogic.ids.ParameterSetID;
import edu.cs.usask.ca.silver.businesslogic.ids.ScenarioID;

/**
 * 
 * This is the interface specification for the local and remote implementations
 * of the Parameter bean.
 * 
 * @author Daniel Funk
 */
public interface ParameterI {

	/**
	 * Adds a parameter to storage, including value and value comment. This
	 * method is typically called whenever parameters are being created from a
	 * source file.
	 * 
	 * @param name
	 *            The parameter name (from source file where available) -
	 *            immutable
	 * @param units
	 *            Unit type - mutable
	 * @param type
	 *            This is the java data type - needed for run-time value
	 *            overriding - immutable
	 * @param associatedClass
	 *            The parent class of a parameter (from source file where
	 *            available) - helps user know which object/class this parameter
	 *            belongs to - immutable
	 * @param descr
	 *            Parameter description - mutable
	 * @param psId
	 *            ParameterSetID of the parameter set this parameter is being
	 *            added to
	 * @param pValue
	 *            Value of the parameter in the given parameter set - immutable
	 *            (for this parameter set)
	 * @param pValComment
	 *            A comment about the chosen value - mutable
	 * @param storage TODO
	 * @return A unique ParameterID
	 * @throws Exception
	 */
	public ParameterID addParameter(String name, String units, String type,
			String associatedClass, String descr, ParameterSetID psId,
			String pValue, String pValComment, StorageI storage) throws Exception;

	/**
	 * Returns a string containing the XML representation of a parameter
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param storage TODO
	 * @return String containing XML representation of a parameter
	 * @throws Exception
	 */
	public String getParameterAsXML(ParameterID pId, StorageI storage) throws Exception;

	/**
	 * Returns the name of a parameter
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param storage TODO
	 * @return The parameter name
	 * @throws Exception
	 */
	public String getName(ParameterID pId, StorageI storage) throws Exception;

	/**
	 * Returns the (data) type of a parameter
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param storage TODO
	 * @return The parameter type
	 * @throws Exception
	 */
	public String getType(ParameterID pId, StorageI storage) throws Exception;

	/**
	 * Returns the units this parameter is measured in
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param storage TODO
	 * @return The parameter units
	 * @throws Exception
	 */
	public String getUnits(ParameterID pId, StorageI storage) throws Exception;

	/**
	 * Returns the associated class/object of a parameter
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param storage TODO
	 * @return The associated class/object of the parameter
	 * @throws Exception
	 */
	public String getAssociatedClass(ParameterID pId, StorageI storage) throws Exception;

	/**
	 * Returns the description of a parameter
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param storage TODO
	 * @return The parameter description
	 * 
	 */
	public String getDescription(ParameterID pId, StorageI storage) throws Exception;

	/**
	 * Returns the parent parameter set of a parameter
	 * 
	 * @param pId
	 *            A unique parameter Id
	 * @param storage TODO
	 * @return The parent parameter set id
	 * 
	 */
	public ParameterSetID getParentParameterSetId(ParameterID pId, StorageI storage) throws Exception;

	/**
	 * Update the Units in which a parameter is measured in the storage layer
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param units
	 *            The (new) units for a parameter
	 * @param storage TODO
	 * @throws Exception
	 */
	public void setUnits(ParameterID pId, String units, StorageI storage) throws Exception;

	/**
	 * Update the parameter description in the storage layer
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param description
	 *            The (new) parameter description
	 * @param storage TODO
	 * @return TODO
	 * @throws Exception
	 */
	public boolean setDescription(ParameterID pId, String description, StorageI storage)
			throws Exception;

	/**
	 * Add a parameter to a scenarion (i.e. assign a value and description)
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param sId
	 *            A unique ScenarioID (identifies a unique parameter set)
	 * @param value
	 *            The value of this parameter in this scenario
	 * @param comment
	 *            A comment about the chosen value
	 * @param storage TODO
	 * @throws Exception
	 */
	public void addParamteterToScenario(ParameterID pId, ScenarioID sId,
			String value, String comment, StorageI storage) throws Exception;

	/**
	 * Removes a parameter from storage
	 * 
	 * @param pId
	 *            A unique ParameterID
	 * @param storage TODO
	 * @return TODO
	 * @throws Exception
	 */
	public boolean deleteParameter(ParameterID pId, StorageI storage) throws Exception;
}
